The CICA Windows Explosion!/The CICA Windows Explosion! - Disc 2.iso/demo/wemdemo4.zip/INFO/ELISP.20

Text File | 1994-09-21 | 51KB | 1,192 lines

Info file elisp, produced by Makeinfo, -*- Text -*- from input file
elisp.texi.

   This file documents GNU Emacs Lisp.

   This is edition 1.03 of the GNU Emacs Lisp Reference Manual,   for
Emacs Version 18.

   Published by the Free Software Foundation, 675 Massachusetts
Avenue,  Cambridge, MA 02139 USA

   Copyright (C) 1990 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.



File: elisp,  Node: Syntax Tables,  Next: Abbrevs,  Prev: Searching and Matching,  Up: Top

Syntax Tables
*************

   A "syntax table" provides Emacs with the information that
determines the syntactic use of each character in a buffer.  This
information is used by the parsing commands, the complex movement
commands, and others to determine where words, symbols, and other
syntactic constructs begin and end.

   A syntax table is a vector of 256 elements; it contains one entry
for each of the 256 ASCII characters of an 8-bit byte.  Each element
is an integer that encodes the syntax of the character in question.

   Syntax tables are used only for moving across text, not for the
GNU Emacs Lisp reader.  GNU Emacs Lisp uses built-in syntactic rules
when reading Lisp expressions, and these rules cannot be changed.

   Each buffer has its own major mode, and each major mode has its
own idea of the syntactic class of various characters.  For example,
in Lisp mode, the character `;' begins a comment, but in C mode, it
terminates a statement.  To support these variations, Emacs makes the
choice of syntax table local to the each buffer.  Typically, each
major mode has its own syntax table and installs that table in each
buffer which uses that mode.  Changing this table alters the syntax
in all those buffers as well as in any buffers subsequently put in
that mode.  Occasionally several similar modes share one syntax table.
*Note Example Major Modes::, for an example of how to set up a syntax
table.

 * Function: syntax-table-p OBJECT
     This function returns `t' if OBJECT is a vector of length 256
     elements.  This means that the vector may be a syntax table.
     However, according to this test, any vector of length 256 is
     considered to be a syntax table, no matter what its contents.

* Menu:

* Syntax Descriptors::       How characters are classified.
* Syntax Table Functions::   How to create, examine and alter syntax tables.
* Parsing Expressions::      Parsing balanced expressions
                                using the syntax table.
* Standard Syntax Tables::   Syntax tables used by various major modes.
* Syntax Table Internals::   How syntax table information is stored.



File: elisp,  Node: Syntax Descriptors,  Next: Syntax Table Functions,  Prev: Syntax Tables,  Up: Syntax Tables

Syntax Descriptors
==================

   This section describes the syntax classes and flags that denote
the syntax of a character, and how they are represented as a "syntax
descriptor", which is a Lisp string that you pass to
`modify-syntax-entry' to specify the desired syntax.

   Emacs defines twelve "syntax classes".  Each syntax table contains
a mapping that puts each character into one class.  There is no
necessary relationship between the class of a character in one syntax
table and its class in any other table.

   Each class is designated by a mnemonic character which serves as
the name of the class when you need to specify a class.  Usually the
designator character is one which is frequently put in that class;
however, its meaning as a designator is unvarying and independent of
how it is actually classified.

   A syntax descriptor is a Lisp string which specifies a syntax
class, a matching character (unused except for parenthesis classes)
and flags.  The first character is the designator for a syntax class.
The second character is the character to match; if it is unused, put
a space there.  Then come the characters for any desired flags.  If
no matching character or flags are needed, one character is sufficient.

   Thus, the descriptor for the character `*' in C mode is `. 23'
(i.e., punctuation, matching character slot unused, second character
of a comment-starter, first character of an comment-ender), and the
entry for `/' is `. 14' (i.e., punctuation, matching character slot
unused, first character of a comment-starter, second character of a
comment-ender).

* Menu:

* Syntax Class Table::      Table of syntax classes.
* Syntax Flags::            Additional flags each character can have.



File: elisp,  Node: Syntax Class Table,  Next: Syntax Flags,  Prev: Syntax Descriptors,  Up: Syntax Descriptors

Table of Syntax Classes
-----------------------

   Here is a summary of the classes, the characters that stand for
them, their meanings, and examples of their use.

 * Syntax class: whitespace character
     "Whitespace characters" (designated with ` ' or `-') separate
     symbols and words from each other.  Typically, whitespace
     characters have no other syntactic use, and multiple whitespace
     characters are syntactically equivalent to one.  Space, tab,
     newline and formfeed are almost always considered whitespace.

 * Syntax class: word constituent
     "Word constituents" (designated with `w') are parts of normal
     English words and are typically used in variable and command
     names in programs.  All upper and lower case letters and the
     digits are typically word constituents.

 * Syntax class: symbol constituent
     "Symbol constituents" (designated with `_') are the extra
     characters that are used in variable and command names along
     with word constituents.  For example, the symbol constituents
     class is used in Lisp mode to indicate that certain characters
     may be part of symbol names even though they are not part of
     English words.  These characters are `$&*+-_<>'.  In standard C,
     the only non-word-constituent character that is valid in symbols
     is underscore (`_').

 * Syntax class: punctuation character
     "Punctuation characters" (`.') are those characters that are
     used as punctuation in English, or are used in some way in a
     programming language to separate symbols from one another.  Most
     programming language modes, including Emacs Lisp mode, have no
     characters in this class since the few characters that are not
     symbol or word constituents all have other uses.

 * Syntax class: open parenthesis character
 * Syntax class: close parenthesis character
     Open and close "parenthesis characters" are characters used in
     dissimilar pairs to surround sentences or expressions.  Such a
     grouping is begun with an open parenthesis character and
     terminated with a close.  Each open parenthesis character
     matches a particular close parenthesis character, and vice
     versa.  Normally, Emacs indicates momentarily the matching open
     parenthesis when you insert a close parenthesis.  *Note
     Blinking::.

     The class of open parentheses is designated with `(', and that
     of close parentheses with `)'.

     In English text, and in C code, the parenthesis pairs are `()',
     `[]', and `{}'.  In Emacs Lisp, the delimiters for lists and
     vectors (`()' and `[]') are classified as parenthesis characters.

 * Syntax class: string quote
     "String quote characters" (designated with `"') is used to
     delimit string constants in many languages, including Lisp and
     C.  The same string quote character appears at the beginning and
     the end of a string.  Such quoted strings do not nest.

     The parsing facilities of Emacs consider a string as a single
     token.  The usual syntactic meanings of the characters in the
     string are suppressed.

     The Lisp modes have two string quote characters: double-quote
     (`"') and vertical bar (`|').  `|' is not used in Emacs Lisp,
     but it is used in Common Lisp.  C also has two string quote
     characters: double-quote for strings, and single-quote (`'') for
     character constants.

     English text has no string quote characters because English is
     not a programming language.  Although quotation marks are used
     in English, we do not want them to turn off the usual syntactic
     properties of other characters in the quotation.

 * Syntax class: escape
     An "escape character" (designated with `\') starts an escape
     sequence such as is used in C string and character constants.
     The character `\' belongs to this class in both C and Lisp.  (In
     C, it is used thus only inside strings, but it turns out to
     cause no trouble to treat it this way throughout C code.)

 * Syntax class: character quote
     A "character quote character" (designated with `/') quotes the
     following character so that it loses its normal syntactic
     meaning.  This differs from an escape character in that only the
     character immediately following is ever affected.

     This class is not currently used in any standard Emacs modes.

 * Syntax class: paired delimiter
     "Paired delimiter characters" (designated with `$') are like
     string quote characters except that the syntactic properties of
     the characters between the delimiters are not suppressed.  Only
     TeX mode uses a paired identical delimiter presently--the `$'
     that begins and ends math mode.

 * Syntax class: expression prefix
     An "expression prefix operator" (designated with `'') is used
     for syntactic operators that are part of an expression if they
     appear next to one but are not part of an adjoining symbol.
     These characters in Lisp include the apostrophe, `'' (used for
     quoting), and the comma, `,' (used in macros).

 * Syntax class: comment starter
 * Syntax class: comment ender
     The "comment starter" and "comment ender" characters are used in
     different languages to delimit comments.  These classes are
     designated with `<' and `>', respectively.

     English text has no comment characters.  In Lisp, the semi-colon
     (`;') starts a comment and a newline or formfeed ends one.



File: elisp,  Node: Syntax Flags,  Prev: Syntax Class Table,  Up: Syntax Descriptors

Syntax Flags
------------

   In addition to the classes, entries for characters in a syntax
table can include flags.  There are four possible flags, represented
by the characters `1', `2', `3', and `4'.  All are used to describe
multi-character comment delimiters.  A flag indicates that the
character for which the entry is being made can *also* be part of a
comment sequence, in addition to the syntactic properties associated
with its character class.  The flags are independent of the class and
each other for the sake of characters such as `*' in C mode, which is
a punctuation character, *and* the second character of a
start-of-comment sequence (`/*'), *and* the first character of an
end-of-comment sequence (`*/').

   The flags for a character C are:

   * `1' means C is the start of a two-character comment start
     sequence.

   * `2' means C is the second character of such a sequence.

   * `3' means C is the start of a two-character comment end sequence.

   * `4' means C is the second character of such a sequence.



File: elisp,  Node: Syntax Table Functions,  Next: Parsing Expressions,  Prev: Syntax Descriptors,  Up: Syntax Tables

Syntax Table Functions
======================

   In this section we describe functions for creating, accessing and
altering syntax tables.

 * Function: make-syntax-table &optional TABLE
     This function constructs a copy of TABLE and returns it.  If
     TABLE is not supplied (or is `nil'), it returns a copy of the
     current syntax table.  Otherwise, an error is signaled if TABLE
     is not a syntax table.

 * Function: copy-syntax-table &optional TABLE
     This function is identical to `make-syntax-table'.

 * Command: modify-syntax-entry CHAR SYNTAX-DESCRIPTOR &optional TABLE
     This function sets the syntax entry for CHAR according to
     SYNTAX-DESCRIPTOR.  The syntax is changed only for TABLE, which
     defaults to the current buffer's syntax table, and not in any
     other syntax table.  The argument SYNTAX-DESCRIPTOR specifies
     the desired syntax; this is a string beginning with a class
     designator character, and optionally containing a matching
     character and flags as well.  *Note Syntax Descriptors::.

     This function always returns `nil'.  The old syntax information
     in the table for this character is discarded.

     An error is signaled if the first character of the syntax
     descriptor is not one of the twelve syntax class designator
     characters.  An error is also signaled if CHAR is not a character.

     Examples:

          ;; Put the space character in class whitespace.
          (modify-syntax-entry ?\  " ")
               => nil

          ;; Make `$' an open parenthesis character,
          ;; with `^' as its matching close.
          (modify-syntax-entry ?$ "(^")
               => nil
          ;; Make `^' a close parenthesis character,
          ;; with `$' as its matching open.
          (modify-syntax-entry ?^ ")$")
               => nil

          ;; Make `/' a punctuation character,
          ;; the first character of a start-comment sequence,
          ;; and the second character of an end-comment sequence.
          ;; This is used in C mode.
          (modify-syntax-entry ?/ ".13")
               => nil

 * Function: char-syntax CHARACTER
     This function returns the syntax class of CHARACTER, represented
     by its mnemonic designator character.  This *only* returns the
     class, not any matching parenthesis or flags.

     An error is signaled if CHAR is not a character.

     The first example shows that the syntax class of space is
     whitespace (represented by a space).  The second example shows
     that the syntax of `/' is punctuation in C-mode.  This does not
     show the fact that it is also a comment sequence character.  The
     third example shows that open parenthesis is in the class of
     open parentheses.  This does not show the fact that it has a
     matching character, `)'.

          (char-to-string (char-syntax ?\ ))
               => " "

          (char-to-string (char-syntax ?/))
               => "."

          (char-to-string (char-syntax ?\())
               => "("

 * Function: set-syntax-table TABLE
     This function makes TABLE the syntax table for the current buffer.
     It returns TABLE.

 * Function: syntax-table
     This function returns the current syntax table, which is the
     table for the current buffer.

 * command: describe-syntax
     This function describes the syntax specifications of the current
     syntax table.  It makes a listing in the `*Help*' buffer, and
     then pops up a window to display it.  It returns `nil'.

     A portion of a description is shown here:

          (describe-syntax)
               => nil

          ---------- Buffer: *Help* ----------
          C-q             \       which means: escape
          C-r .. C-_              which means: whitespace
          !               .       which means: punctuation
          (               ()      which means: open, matches )
          )               )(      which means: close, matches (
          * .. +          _       which means: symbol
          ,               .       which means: punctuation
          -               _       which means: symbol
          .               .       which means: punctuation
          /               . 13    which means: punctuation,
                    is the first character of a comment-start sequence,
                    is the first character of a comment-end sequence
          0 .. 9          w       which means: word
          ---------- Buffer: *Help* ----------



File: elisp,  Node: Parsing Expressions,  Next: Standard Syntax Tables,  Prev: Syntax Table Functions,  Up: Syntax Tables

Parsing and Moving Over Balanced Expressions
============================================

   Here are several functions for parsing and scanning balanced
expressions.  The syntax table controls the interpretation of
characters, so these functions can be used for Lisp expressions when
in Lisp mode and for C expressions when in C mode.  *Note List
Motion::, for convenient higher-level functions for moving over
balanced expressions.

 * Function: parse-partial-sexp START LIMIT &optional TARGET-DEPTH
          STOP-BEFORE STATE
     This function parses an expression in the current buffer
     starting at START, not scanning past LIMIT.  Parsing stops at
     LIMIT or when certain criteria described below are met; point is
     set to the location where parsing stops.  The value returned is
     a description of the status of the parse at the point where it
     stops.

     Normally, START is assumed to be the top level of an expression
     to be parsed, such as the beginning of a function definition.
     Alternatively, you might wish to resume parsing in the middle of
     an expression.  To do this, you must provide a STATE argument
     that describes the initial status of parsing.  If STATE is
     omitted (or `nil'), parsing assumes that START is the beginning
     of a new parse at level 0.

     If the third argument TARGET-DEPTH is non-`nil', parsing stops
     if the depth in parentheses becomes equal to TARGET-DEPTH.  The
     depth starts at 0, or at whatever is given in STATE.

     If the fourth argument STOP-BEFORE is non-`nil', parsing stops
     when it comes to any character that starts a sexp.

     The fifth argument STATE is a seven-element list of the same
     form as the value of this function, described below.  The return
     value of one call may be used to initialize the state of the
     parse on another call to `parse-partial-sexp'.

     The result is a list of seven elements describing the final
     state of the parse:

       1. The depth in parentheses, starting at 0.

       2. The character position of the start of the innermost
          containing parenthetical grouping; `nil' if none.

       3. The character position of the start of the last complete
          subexpression terminated; `nil' if none.

       4. Non-`nil' if inside a string.  (It is the character that
          will terminate the string.)

       5. `t' if inside a comment.

       6. `t' if point is just after a quote character.

       7. The minimum parenthesis depth encountered during this scan.

     Elements 1, 4, 5, and 6 are significant in the argument STATE.

     This function is used to determine how to indent lines in
     programs written in languages that have nested parentheses.

 * Function: scan-lists FROM COUNT DEPTH
     This function scans forward COUNT balanced parenthetical
     groupings from character number FROM.  It returns the character
     number of the position thus found.

     If DEPTH is nonzero, parenthesis depth counting begins from that
     value.  The only candidates for stopping are places where the
     depth in parentheses becomes zero; `scan-lists' counts COUNT
     such places and then stops.  Thus, a positive value for DEPTH
     means go out levels of parenthesis.

     Comments are ignored if `parse-sexp-ignore-comments' is non-`nil'.

     If the beginning or end of the buffer (or its accessible
     portion) is reached and the depth is not zero, an `end-of-file'
     error is signaled.  If the depth is zero but the count is not
     used up, `nil' is returned.

 * Function: scan-sexps FROM COUNT
     Scan from character number FROM by COUNT balanced expressions.
     It returns the character number of the position thus found.

     Comments are ignored if `parse-sexp-ignore-comments' is non-`nil'.

     If the beginning or end of (the accessible part of) the buffer
     is reached in the middle of a parenthetical grouping, an
     `end-of-file' error is signaled.  If the beginning or end is
     reached between groupings but before count is used up, `nil' is
     returned.

 * Function: backward-prefix-chars
     This function moves point backward over any number of chars with
     expression prefix syntax.

 * Variable: parse-sexp-ignore-comments
     If the value is non-`nil', then comments are treated as
     whitespace by the functions in this section and by `forward-sexp'.

     This works only when the comment terminator is something like
     `*/', and appears only to end a comment.  If comments are
     terminated by newlines, you must make this variable `nil', since
     not every newline is the end of a comment.  (In version 19, this
     limitation is removed.)



File: elisp,  Node: Standard Syntax Tables,  Next: Syntax Table Internals,  Prev: Parsing Expressions,  Up: Syntax Tables

Some Standard Syntax Tables
===========================

   Each of the major modes in Emacs has its own syntax table.  Here
are several of them:

 * Function: standard-syntax-table
     This function returns the standard syntax table, which is the
     syntax table used in Fundamental mode.

 * Variable: text-mode-syntax-table
     The value of this variable is the syntax table used in Text mode.

 * Variable: c-mode-syntax-table
     The value of this variable is the syntax table in use in C-mode
     buffers.

 * Variable: emacs-lisp-mode-syntax-table
     The value of this variable is the syntax table used in Emacs
     Lisp mode by editing commands.  (It has no effect on the Lisp
     `read' function.)



File: elisp,  Node: Syntax Table Internals,  Prev: Standard Syntax Tables,  Up: Syntax Tables

Syntax Table Internals
======================

   Each element of a syntax table is an integer that translates into
the full meaning of the entry: class, possible matching character,
and flags.  However, it is not common for a programmer to work with
the entries directly in this form since the Lisp-level syntax table
functions usually work with syntax descriptors (*note Syntax
Descriptors::.).

   The low 8 bits of each element of a syntax table indicates the
syntax class.

Integer
     Class

0
     whitespace

1
     punctuation

2
     word

3
     symbol

4
     open parenthesis

5
     close parenthesis

6
     expression prefix

7
     string quote

8
     paired delimiter

9
     escape

10
     character quote

11
     comment-start

12
     comment-end

   The next 8 bits are the matching opposite parenthesis (if the
character has parenthesis syntax); otherwise, they are not meaningful.
The next 4 bits are the flags.



File: elisp,  Node: Abbrevs,  Next: Processes,  Prev: Syntax Tables,  Up: Top

Abbrevs And Abbrev Expansion
****************************

   An abbreviation or "abbrev" is a string of characters that may be
expanded to a longer string.  The user can insert the abbrev string
and find it replaced automatically with the expansion of the abbrev.
This saves typing.

   The set of abbrevs currently in effect is recorded in an "abbrev
table".  Each buffer has a local abbrev table, but normally all
buffers in the same major mode share one abbrev table.  There is also
a global abbrev table.  Normally both are used.

   An abbrev table is represented as an obarray containing a symbol
for each abbreviation.  The symbol's name is the abbreviation.  Its
value is the expansion; its function definition is the hook; its
property list cell contains the use count, the number of times the
abbreviation has been expanded.  Because these symbols are not
inturned in the usual obarray, they will never appear as the result
of reading a Lisp expression; in fact, they will never be used except
by the code that handles abbrevs.  Therefore, it is safe to use them
in an extremely nonstandard way.  *Note Creating Symbols::.

   For the user-level commands for abbrevs, see *Note : (emacs)Abbrevs.

* Menu:

* Abbrev Mode::                 Setting up Emacs for abbreviation.
* Tables: Abbrev Tables.        Creating and working with abbrev tables.
* Defining Abbrevs::            Specifying abbreviations and their expansions.
* Files: Abbrev Files.          Saving abbrevs in files.
* Expansion: Abbrev Expansion.  Controlling expansion; expansion subroutines.
* Standard Abbrev Tables::      Abbrev tables used by various major modes.



File: elisp,  Node: Abbrev Mode,  Next: Abbrev Tables,  Prev: Abbrevs,  Up: Abbrevs

Setting Up Abbrev Mode
======================

   Abbrev mode is a minor mode controlled by the value of the
variable `abbrev-mode'.

 * Variable: abbrev-mode
     A non-`nil' value of this variable turns on the automatic
     expansion of abbrevs when their abbreviations are inserted into
     a buffer.  If the value is `nil', abbrevs may be defined, but
     they are not expanded automatically.

     This variable automatically becomes local when set in any fashion.

 * Variable: default-abbrev-mode
     This is the value `abbrev-mode' for buffers that do not override
     it.  This is the same as `(default-value 'abbrev-mode)'.



File: elisp,  Node: Abbrev Tables,  Next: Defining Abbrevs,  Prev: Abbrev Mode,  Up: Abbrevs

Abbrev Tables
=============

   This section describes how to create and manipulate abbrev tables.

 * Function: make-abbrev-table
     This function creates and returns a new, empty abbrev table--an
     obarray containing no symbols.  It is a vector filled with `nil's.

 * Function: clear-abbrev-table TABLE
     This function undefines all the abbrevs in abbrev table TABLE,
     leaving it empty.  The function returns `nil'.

 * Function: define-abbrev-table TABNAME DEFINITIONS
     This function defines TABNAME (a symbol) as an abbrev table
     name, i.e., as a variable whose value is an abbrev table.  It
     defines abbrevs in the table according to DEFINITIONS, a list of
     elements of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'.
     The value is always `nil'.

 * Variable: abbrev-table-name-list
     This is a list of symbols whose values are abbrev tables.
     `define-abbrev-table' adds the new abbrev table name to this list.

 * Function: insert-abbrev-table-description NAME HUMAN
     This function inserts before point a description of the abbrev
     table named NAME.  The argument NAME is a symbol whose value is
     an abbrev table.  The value is always `nil'.

     If HUMAN is non-`nil', a human-oriented description is inserted.
     Otherwise the description is a Lisp expression--a call to
     `define-abbrev-table' which would define NAME exactly as it is
     currently defined.



File: elisp,  Node: Defining Abbrevs,  Next: Abbrev Files,  Prev: Abbrev Tables,  Up: Abbrevs

Defining Abbrevs
================

   These functions define an abbrev in a specified abbrev table.
`define-abbrev' is the low-level basic function, while `add-abbrev'
is used by commands that ask for information from the user.

 * Function: add-abbrev TABLE TYPE ARG
     This function adds an abbreviation to abbrev table TABLE.  The
     argument TYPE is a string describing in English the kind of
     abbrev this will be (typically, `"global"' or
     `"mode-specific"'); this is used in prompting the user.  The
     argument ARG is the number of words in the expansion.

     The return value is the symbol which internally represents the
     new abbrev, or `nil' if the user declines to redefine an
     existing abbrev.

 * Function: define-abbrev TABLE NAME EXPANSION HOOK
     This function defines an abbrev in TABLE named NAME, to expand
     to EXPANSION, and call HOOK.  The return value is an uninterned
     symbol which represents the abbrev inside Emacs; its name is NAME.

     The argument NAME should be a string.  The argument EXPANSION
     should be a string, or `nil', to undefine the abbrev.

     The argument HOOK is a function or `nil'.  If HOOK is non-`nil',
     then it is called with no arguments after the abbrev is replaced
     with EXPANSION; point is located at the end of EXPANSION.

     The use count of the abbrev is initialized to zero.

 * User Option: only-global-abbrevs
     If this variable is non-`nil', it means that the user plans to
     use global abbrevs only.  This tells the commands that define
     mode-specific abbrevs to define global ones instead.  This
     variable does not alter the functioning of the functions in this
     section; it is examined by their callers.



File: elisp,  Node: Abbrev Files,  Next: Abbrev Expansion,  Prev: Defining Abbrevs,  Up: Abbrevs

Saving Abbrevs in Files
=======================

   A file of saved abbrev definitions is actually a file of Lisp code.
The abbrevs are saved in the form of a Lisp program to define the
same abbrev tables with the same contents.  Therefore, you can load
the file with `load' (*note How Programs Do Loading::.).  However,
the function `quietly-read-abbrev-file' is provided as a more
convenient interface.

   User-level facilities such as `save-some-buffers' can save abbrevs
in a file automatically, under the control of variables described here.

 * User Option: abbrev-file-name
     This is the default file name for reading and saving abbrevs.

 * Function: quietly-read-abbrev-file FILENAME
     This function reads abbrev definitions from a file named
     FILENAME, previously written with `write-abbrev-file'.  If
     FILENAME is `nil', the file specified in `abbrev-file-name' is
     used.  `save-abbrevs' is set to `t' so that changes will be saved.

     This function does not display any messages.  It returns `nil'.

 * User Option: save-abbrevs
     A non-`nil' value for `save-abbrev' means that Emacs should save
     abbrevs when files are saved.  `abbrev-file-name' specifies the
     file to save the abbrevs in.

 * Variable: abbrevs-changed
     This variable is set non-`nil' by defining or altering any
     abbrevs.  This serves as a flag for various Emacs commands to
     offer to save your abbrevs.

 * Command: write-abbrev-file FILENAME
     Save all abbrev definitions, in all abbrev tables, in the file
     FILENAME as a Lisp program which will define the same abbrevs
     when loaded.  This function returns `nil'.



File: elisp,  Node: Abbrev Expansion,  Next: Standard Abbrev Tables,  Prev: Abbrev Files,  Up: Abbrevs

Looking Up and Expanding Abbreviations
======================================

   Abbrevs are usually expanded by commands for interactive use, or
automatically by `self-insert'.  This section describes the
subroutines used in writing such functions, as well as the variables
they use for communication.

 * Function: abbrev-symbol ABBREV TABLE
     This function returns the symbol representing the abbrev named
     ABBREV.  The value returned is `nil' if that abbrev is not
     defined.  The optional second argument TABLE is the abbrev table
     to look it up in.  By default, this function tries first the
     current buffer's local abbrev table, and second the global
     abbrev table.

 * User Option: abbrev-all-caps
     When this is set non-`nil', an abbrev entered entirely in upper
     case is expanded using all upper case.  Otherwise, an abbrev
     entered entirely in upper case is expanded by capitalizing each
     word of the expansion.

 * Function: abbrev-expansion ABBREV &optional TABLE
     This function returns the string that ABBREV would expand into
     (as defined by the abbrev tables used for the current buffer).
     The optional argument TABLE specifies the abbrev table to use;
     if it is specified, the abbrev is looked up in that table only.

 * Variable: abbrev-start-location
     This is the buffer position for `expand-abbrev' to use as the
     start of the next abbrev to be expanded.  `nil' means use the
     word before point as the abbrev.  `abbrev-start-location' is set
     to `nil' each time `expand-abbrev' is called.  This variable is
     set by `abbrev-prefix-mark'.

 * Variable: abbrev-start-location-buffer
     The value of this variable is the buffer for which
     `abbrev-start-location' has been set.  Trying to expand an
     abbrev in any other buffer clears `abbrev-start-location'.  This
     variable is set by `abbrev-prefix-mark'.

 * Variable: last-abbrev
     This is the `abbrev-symbol' of the last abbrev expanded.  This
     information is left by `expand-abbrev' for the sake of the
     `unexpand-abbrev' command.

 * Variable: last-abbrev-location
     This is the location of the last abbrev expanded.  This contains
     information left by `expand-abbrev' for the sake of the
     `unexpand-abbrev' command.

 * Variable: last-abbrev-text
     This is the exact expansion  text of the last abbrev expanded,
     as results from case conversion.  Its value is `nil' if the
     abbrev has already been unexpanded.  This contains information
     left by `expand-abbrev' for the sake of the `unexpand-abbrev'
     command.



File: elisp,  Node: Standard Abbrev Tables,  Prev: Abbrev Expansion,  Up: Abbrevs

Standard Abbrev Tables
======================

   Here we list the variables that hold the abbrev tables for the
preloaded major modes of Emacs.

 * Variable: global-abbrev-table
     This is the abbrev table for mode-independent abbrevs.  The
     abbrevs defined in it apply to all buffers.  Each buffer may
     also have a local abbrev table, whose abbrev definitions take
     precedence over those in the global table.

 * Variable: local-abbrev-table
     The value of this buffer-local variable is the (mode-specific)
     abbreviation table of the current buffer.

 * Variable: fundamental-mode-abbrev-table
     This is the local abbrev table used in Fundamental mode.  It is
     the local abbrev table in all buffers in Fundamental mode.

 * Variable: text-mode-abbrev-table
     This is the local abbrev table used in Text mode.

 * Variable: c-mode-abbrev-table
     This is the local abbrev table used in C mode.

 * Variable: lisp-mode-abbrev-table
     This is the local abbrev table used in Lisp mode and Emacs Lisp
     mode.



File: elisp,  Node: Processes,  Next: System Interface,  Prev: Abbrevs,  Up: Top

Processes
*********

   In the terminology of operating systems, a "process" is a space in
which a program can execute.  Emacs runs in a process.  Emacs Lisp
programs can invoke other programs in processes of their own.  These
are called "subprocesses" or "child processes" of the Emacs process,
which is their "parent process".

   A subprocess of Emacs may be "synchronous" or "asynchronous".
depending on how it is created.  When you create a synchronous
subprocess, the Lisp program waits for the subprocess to terminate
before continuing execution.  When you create an asynchronous
subprocess, it can run in parallel with the Lisp program.  This kind
of subprocess is represented within Emacs by a Lisp object which is
also called a "process".  Lisp programs can use this object to
communicate with the subprocess or to control it.  For example, you
can send signals, obtain status information, receive output from the
process, or send input to it.

 * Function: processp OBJECT
     This function returns `t' if OBJECT is a process, `nil' otherwise.

* Menu:

* Subprocess Creation::      Functions that start subprocesses.
* Synchronous Processes::    Details of using synchronous subprocesses.
* Asynchronous Processes::   Starting up an asynchronous subprocess.
* Deleting Processes::       Eliminating an asynchronous subprocess.
* Process Information::      Accessing run-status and other attributes.
* Input to Processes::       Sending input to an asynchronous subprocess.
* Signals to Processes::     Stopping, continuing or interrupting
                               an asynchronous subprocess.
* Output from Processes::    Collecting output from an asynchronous subprocess.
* Sentinels::                Sentinels run when process run-status changes.
* VMS Subprocesses::         VMS has completely different subprocess features.
* TCP::                      Opening network connections.



File: elisp,  Node: Subprocess Creation,  Next: Synchronous Processes,  Prev: Processes,  Up: Processes

Functions that Create Subprocesses
==================================

   There are three functions that create a new Unix subprocess in
which to run a program.  One of them, `start-process', creates an
asynchronous process and returns a process object (*note Asynchronous
Processes::.).  The other two, `call-process' and
`call-process-region', create a synchronous process and do not return
a process object (*note Synchronous Processes::.).

   Synchronous and asynchronous processes are explained in following
sections.  Since the three functions are all called in a similar
fashion, their common arguments are described here.

   In all cases, the program to be run is specified with the
function's PROGRAM argument.  An error is signaled if the file is not
found or cannot be executed.  The actual file containing the program
is found by following normal Unix rules: if an absolute file name is
given, then the program must be found in the specified file; if a
relative file name is given, then the directories in `exec-path' are
searched sequentially for a suitable file.  The variable `exec-path'
is initialized when Emacs is started, based on the value of the
environment variable `PATH'.  The standard Unix abbreviations, `~',
`.', and `..', are interpreted as usual, but environment variable
substitutions (`$HOME', etc.) are not recognized; use
`substitute-in-file-name' to perform them (*note File Name
Expansion::.).

   Each of the subprocess-creating functions has a BUFFER-OR-NAME
argument which specifies where the standard output from the program
will go.  If BUFFER-OR-NAME is `nil', then the output will be
discarded (by directing it to `/dev/null') unless a filter function
is specified to handle it.  (*Note Filter Functions::, and *Note
Streams::.)  Normally, you should avoid having multiple processes
send output to the same buffer because the outputs will be intermixed
randomly.

   All three of the subprocess-creating functions have a `&rest'
argument, ARGS.  The ARGS must all be strings, and they are supplied
to PROGRAM as separate command line arguments.  Wildcard characters
and other shell constructs are not allowed in these strings, since
they are passed directly to the specified program.  *Note:* the
argument PROGRAM contains only the name of the program; it may not
contain any command-line arguments.  Such arguments must be provided
via ARGS.

   The subprocess gets its current directory from the value of
`default-directory' (*note File Name Expansion::.).

   The subprocess inherits its environment from Emacs; but you can
specify overrides for it with `process-environment'.

 * Variable: process-environment
     This variable is a list of strings to append to the environment
     of processes as they are created.  Each string assigns a value
     to a shell environment variable.  (This applies both to
     asynchronous and synchronous processes.)

          process-environment
          => ("l=/usr/stanford/lib/gnuemacs/lisp"
              "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
              "USER=lewis"
              "TERM=ibmapa16"
              "SHELL=/bin/csh"
              "HOME=/user/lewis")

 * Variable: exec-directory
     The value of this variable is the name of a directory (a string)
     that contains programs that come with GNU Emacs, that are
     intended for Emacs to invoke.  The program `loadst' is an
     example of such a program; it is used by the `display-time'
     command to print the current time (and certain other
     information) once per minute.

     The default value is the name of a directory whose name ends in
     `etc'.  We call the directory `emacs/etc', since its name
     usually ends that way.  We sometimes refer to "the directory
     `emacs/etc'," when strictly speaking we ought to say, "the
     directory named by the variable `exec-directory'."  Most of the
     time, there is no difference.

 * User Option: exec-path
     The value of this variable is a list of directories to search
     for programs to run in subprocesses.  Each element is either the
     name of a directory (i.e., a string), or `nil', which stands for
     the default directory (which is the value of `default-directory').

     The value of `exec-path' is used by `call-process' and
     `start-process' when the PROGRAM argument is not an absolute
     file name.



File: elisp,  Node: Synchronous Processes,  Next: Asynchronous Processes,  Prev: Subprocess Creation,  Up: Processes

Creating a Synchronous Process
==============================

   After a "synchronous process" is created, Emacs waits for the
process to terminate before continuing.  Starting Dired is an example
of this: it runs `ls' in a synchronous process, then modifies the
output slightly.  Because the process is synchronous, the entire
directory listing arrives in the buffer before Emacs tries to do
anything with it.

   While Emacs waits for the synchronous subprocess to terminate, the
user can quit by typing `C-g', and the process is killed by sending
it a `SIGKILL' signal.  *Note Quitting::.

   The synchronous subprocess functions return `nil' in version 18.
In version 19, they will return an indication of how the process
terminated.

 * Function: call-process PROGRAM &optional INFILE BUFFER-OR-NAME
          DISPLAY &rest ARGS
     This function calls PROGRAM in a separate process and waits for
     it to finish.

     The standard input for the process comes from file INFILE if
     INFILE is not `nil' and from `/dev/null' otherwise.  The process
     output gets inserted in buffer BUFFER-OR-NAME before point, if
     that argument names a buffer.  If BUFFER-OR-NAME is `t', output
     is sent to the current buffer; if BUFFER-OR-NAME is `nil',
     output is discarded.

     If BUFFER-OR-NAME is the integer 0, the output is discarded and
     `call-process' returns immediately.  In this case, the process
     is not truly synchronous, since it can run in parallel with
     Emacs; but you can think of it as synchronous in that Emacs is
     essentially finished with the subprocess as soon as this
     function returns.

     If DISPLAY is non-`nil', then `call-process' redisplays the
     buffer as output is inserted.  Otherwise the function does no
     redisplay, and the results become visible on the screen only
     when Emacs redisplays that buffer in the normal course of events.

     The remaining arguments, ARGS, are strings that are supplied as
     the command line arguments for the program.

     The examples below are both run with the buffer `foo' current.

          (call-process "pwd" nil t)
               => nil

          ---------- Buffer: foo ----------
          /usr/user/lewis/manual
          ---------- Buffer: foo ----------

          (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
               => nil

          ---------- Buffer: bar ----------
          lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh

          ---------- Buffer: bar ----------

     The `dired-readin' function contains a good example of the use
     of `call-process':

          (call-process "ls" nil buffer nil dired-listing-switches dirname)

 * Function: call-process-region START END PROGRAM &optional DELETE
          BUFFER-OR-NAME DISPLAY &rest ARGS
     This function sends the text between START to END as standard
     input to a process running PROGRAM.  It deletes the text sent if
     DELETE is non-`nil', which may be useful when the output is
     going to be inserted back in the current buffer.

     If BUFFER-OR-NAME names a buffer, the output is inserted in that
     buffer at point.  If BUFFER-OR-NAME is `t', the output is sent
     to the current buffer.  If BUFFER-OR-NAME is `nil', the output
     is discarded.  If BUFFER-OR-NAME is the integer 0, the output is
     discarded and `call-process' returns immediately, as in
     `call-process'.

     If DISPLAY is non-`nil', then `call-process-region' redisplays
     the buffer as output is inserted.  Otherwise the function does
     no redisplay, and the results become visible on the screen only
     when Emacs redisplays that buffer in the normal course of events.

     The remaining arguments, ARGS, are strings that are supplied as
     the command line arguments for the program.

     In the following example, we use `call-process-region' to run
     the `cat' utility, with standard input being the first five
     characters in buffer `foo' (the word `input').  `cat' copies its
     standard input into its standard output.  Since the argument
     BUFFER-OR-NAME is `t', this output is inserted in the current
     buffer.

          ---------- Buffer: foo ----------
          input-!-
          ---------- Buffer: foo ----------

          (call-process-region 1 6 "cat" nil t)
               => nil

          ---------- Buffer: foo ----------
          inputinput-!-
          ---------- Buffer: foo ----------

     The `shell-command-on-region' command uses `call-process-region'
     like this:

          (call-process-region start end
                               shell-file-name    ; Name of program.
                               nil                ; Do not delete region.
                               buffer             ; Send output to `buffer'.
                               nil                ; No redisplay during output.
                               "-c" command)      ; Arguments for the shell.



File: elisp,  Node: Asynchronous Processes,  Next: Deleting Processes,  Prev: Synchronous Processes,  Up: Processes

Creating an Asynchronous Process
================================

   After an "asynchronous process" is created, Emacs and the Lisp
program can continue running immediately.  The process may thereafter
run in parallel with Emacs, and the two may communicate with each
other using the functions described in following sections.  Here we
describe how to create an asynchronous process, with `start-process'.

 * Function: start-process NAME BUFFER-OR-NAME PROGRAM &rest ARGS
     This function creates a new asynchronous subprocess and starts
     the program PROGRAM running in it.  It returns a process object
     that stands for the new subprocess for Emacs Lisp programs.  The
     argument NAME specifies the name for the process object; if a
     process with this name already exists, then NAME is modified (by
     adding `<1>', etc.) to be unique.  The buffer BUFFER-OR-NAME is
     the buffer to associate with the process.

     The remaining arguments, ARGS, are strings that are supplied as
     the command line arguments for the program.

     In the example below, the first process is started and runs
     (rather, sleeps) for 100 seconds.  Meanwhile, the second process
     is started, given the name `my-process<1>' for the sake of
     uniqueness.  It inserts the directory listing at the end of the
     buffer `foo', before the first process finishes.  Then it
     finishes, and a message to that effect is inserted in the
     buffer.  Much later, the first process finishes, and another
     message is inserted in the buffer for it.

          (start-process "my-process" "foo" "sleep" "100")
               => #<process my-process>

          (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
               => #<process my-process<1>>

          ---------- Buffer: foo ----------
          total 2
          lrwxrwxrwx  1 lewis          14 Jul 22 10:12 gnuemacs --> /emacs
          -rwxrwxrwx  1 lewis          19 Jul 30 21:02 lemon

          Process my-process<1> finished

          Process my-process finished
          ---------- Buffer: foo ----------

 * Variable: process-connection-type
     This variable controls the type of device used to communicate
     with asynchronous subprocesses.  If it is `nil', then pipes are
     used.  If it is `t', then PTYs are used (or pipes if PTYs not
     supported).

     PTYs are usually preferable for processes visible to the user,
     as in Shell mode, because they allow job control (`C-c', `C-z',
     etc.) to work between the process and its children whereas pipes
     do not.  For subprocesses used for internal purposes by
     programs, it is often better to use a pipe, because they are
     more efficient.  In addition, the total number of PTYs is
     limited on many systems and it is good not to waste them.

     The value `process-connection-type' is used when `start-process'
     is called, so in order to change it for just one call of
     `start-process', temporarily rebind it with `let'.

          (let ((process-connection-type nil))  ; Use a pipe.
            (start-process ...))